home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / program / 569 / gemfst17 / gemfbind.doc < prev    next >
Text File  |  1992-06-01  |  16KB  |  315 lines
  1.  
  2. ***************************************************************************
  3.                                 GEMFAST
  4.                        Public Domain GEM bindings
  5.                               by Ian Lepore
  6. ***************************************************************************
  7.  
  8. This document provides general background on the GEMFAST bindings system,
  9. installation and usage information, and documents some of the internals 
  10. applicable to the C programmer.
  11.  
  12. ---------------------------------------------------------------------------
  13.                             DOCUMENT CONTENTS
  14. ---------------------------------------------------------------------------
  15.  
  16.  1.0  -  Packing List
  17.  2.0  -  Background
  18.  3.0  -  Functions supported by the bindings
  19.  4.0  -  Installation and Usage
  20.  5.0  -  About the GEMFAST.H header file
  21.  6.0  -  Notes
  22.  7.0  -  Bugs
  23.  8.0  -  Support
  24.  9.0  -  About the (non-existant) copyright
  25.  
  26. ---------------------------------------------------------------------------
  27.  1.0                          PACKING LIST 
  28.                  (xx = version, eg '10' = version 1.0)
  29. ---------------------------------------------------------------------------
  30.  
  31.      GEMFSTxx.ARC     - The runtime system, includes the following...
  32.         AESFAST.A     - The AES bindings library.
  33.         VDIFAST.A     - The VDI bindings library.
  34.         GEMFAST.H     - The C-language header file for use with GEMFAST.
  35.         GEMF_Vxx.DOC  - Version-specific release notes and revision history.
  36.         GEMUTIL.DOC   - Documentation on non-standard utility functions.
  37.         GEMXTEND.DOC  - Documentation on GEM extensions (Atari's and mine).
  38.         GEMFBIND.DOC  - Installation and usage documentation.
  39.  
  40.      GEMFSCxx.ARC    - Source code for the package.  
  41.         AESSRCxx.ARC - Source code for the AES bindings and utilities.
  42.         VDISRCxx.ARC - Source code for the VDI bindings.
  43.  
  44.      GEMFXMxx.ARC    - Example programs.
  45.         MINICOLR.ARC - Example desk accessory, a mini color pallete control.
  46.         MEMFIND.ARC  - Example dialog-based program, displays free memory.
  47.         WINDXMPL.ARC - Example of object tree display in a window.
  48.         
  49.      GEMFUTxx.ARC    - The GEMFAST utilities in C source code format.
  50.      
  51. ---------------------------------------------------------------------------
  52. 2.0                            BACKGROUND
  53. ---------------------------------------------------------------------------
  54.  
  55. These binding libraries were written to address two needs: 1) The world 
  56. needed a good set of free GEM bindings to complement the various PD C
  57. compilers that are available, and 2) The bindings available with most 
  58. commercial compilers aren't so hot either.
  59.  
  60. These routines have been written to be faster than your typical GEM 
  61. bindings.  As a secondary consideration, I tried to make them smaller as 
  62. well.  When you recompile an application using these libararies, you 
  63. should notice a drop in program size, and the link phase of the compile 
  64. should run faster (your mileage may vary).  The design goals included 
  65. using as little bss and data memory as possible (the stack is used for
  66. temporary storage as needed), and that references requiring relocation 
  67. fixup be kept to a minimum.
  68.  
  69. These bindings are known to be compatible with Alcyon C, Sozobon C, and 
  70. Laser C.  They should be compatible with any compiler/linker system 
  71. which uses 'DRI-standard' object & library file formats.  In addition,
  72. the C source code version of the utilities should work with any C compiler.
  73. There will be support for MWC *someday*, but I will NOT commit to a date.
  74.  
  75. ---------------------------------------------------------------------------
  76. 3.0               FUNCTIONS SUPPORTED IN THESE BINDINGS
  77. ---------------------------------------------------------------------------
  78.  
  79. The VDIFAST library includes most of the functions documented in the 
  80. Digital Research publication _GEM Programmer's Guide Vol 1: VDI_.  Some 
  81. of the VDI functions are missing from the VDIFAST library, 
  82. notably the 'Polaroid Pallete' stuff, the v_cellarray() functions, and 
  83. similar rarely-used items.  There is now a 'roll your own' VDI function,
  84. vdicall().  This lets you write C code to access VDI functions which are
  85. not directly supported by the bindings (such as GDOS functions).  It is
  86. documented in GEMXTEND.DOC.
  87.  
  88. The AESFAST library includes all AES functions documented in the DRI 
  89. publication _GEM Programmer's Guide Vol 2: AES_.  Also included are the 
  90. 'standard' AES utility functions (rc_intersect, etc), and a collection 
  91. of non-standard utilities of my own.  The document file GEMUTIL.DOC 
  92. describes the utility functions.  The AES functions that Atari added 
  93. beginning with TOS 1.4 are also supported.  See GEMXTEND.DOC for more
  94. information.  (As of GemFast release 1.4, a new calling standard for AES
  95. functions has been added.  These are documented in GEMXTEND.DOC).
  96.  
  97. The DRI documents cited above are the definitive reference for the 
  98. standard AES & VDI functions.  If you are using other documents (such as 
  99. Abacus books) there may be some variations between your documents and 
  100. the libraries.  Sorry, I decided it was safer to use the original DRI 
  101. docs as my source of info.  TOS 1.4 functions were built to the
  102. specs in the TOS 1.4 developer's release notes, and thus ARE SUBJECT TO
  103. CHANGE, depending on what Atari does with the final release of TOS 1.4.
  104.  
  105. ---------------------------------------------------------------------------
  106. 4.0                       INSTALLATION AND USAGE
  107. ---------------------------------------------------------------------------
  108.  
  109. Copy the VDIFAST.A and AESFAST.A files to the drive and path where your 
  110. linker will look for runtime-library files.  (EG:  \sozobon\lib). Copy 
  111. the GEMFAST.H file to the drive and path where your compiler looks for 
  112. include files (EG: \sozobon\include).
  113.  
  114. If you are using the Atari 'aln' linker, you will need to use aln's 
  115. DOINDEX program to create .NDX files for each of the libraries.  ALWAYS
  116. BE SURE TO RE-INDEX THE LIBRARY WHEN YOU INSTALL A NEW VERSION OF THE
  117. BINDINGS!
  118.  
  119. To link with the GEMFAST libraries, just enter the library names on the 
  120. command line for the linker program.  For example (using Sozobon):
  121.  
  122.   ld -o myprog.prg dstart.o myprog.o dlibs.a vdifast.a aesfast.a
  123.                          or
  124.   cc -o myprog.prg myprog.c vdifast.a aesfast.a
  125.  
  126. It should not matter where on the command line the names of the GEMFAST 
  127. libs appear:  each library is self-contained, and the linker will not 
  128. have to resolve references between libraries.  No special code is needed 
  129. in your startup object file; you may continue to use whatever startup file
  130. (dstart.o, apstart.o, etc) you currently use.  Also, unlike some GEM 
  131. bindings, you do NOT need to include the VDI bindings libarary if your 
  132. program uses only AES function calls.
  133.  
  134. (An aside:  I've seen a lot of programs that open a VDI workstation, and 
  135. then use only AES functions within the program.  If you use only AES 
  136. functions, you do NOT need to open a VDI virtual workstation.)
  137.  
  138. ---------------------------------------------------------------------------
  139. 5.0                   ABOUT THE GEMFAST HEADER FILE
  140. ---------------------------------------------------------------------------
  141.  
  142. All VDI and AES functions return an 'int' or are of type 'void' 
  143. (returning nothing).  Given the lack of ST C compilers which support 
  144. function prototyping, a header file full of 'extern int xxx()' type 
  145. declarations is a waste of compile time.  The GEMFAST.H file contains 
  146. constants and structures commonly used in GEM programming.
  147.  
  148. If your current bindings system uses OBDEFS.H and GEMDEFS.H, remove the
  149. #include statements for those files, and insert #include <gemfast.h> in
  150. your source code.  While it is possible to continue using your old header
  151. files, your code will become less compatible as future versions of GEMFAST
  152. are released, as the GEMFAST.H file now contains #defines to redirect some
  153. old utility function names to the new names.  Also, the GEMFAST.H file
  154. contains #define GEMFAST_H 1, and code is gonna hit the PD pretty soon that
  155. requires that constant to be set to correctly detect that the GEMFAST
  156. bindings are being used.
  157.  
  158. If you have a lot of existing code that #include's OBDEFS and GEMDEFS, you
  159. can painlessly upgrade all your program to GEMFAST by creating an empty
  160. OBDEFS.H file, and a new GEMDEFS.H file that contains only one line,
  161. "#include <GEMFAST.H>"; this will effectively convert all your existing code.
  162.  
  163. The GEMFAST.SH file is included for those brave (foolish?) souls like 
  164. myself who do GEM programming in assembler.  The file is essentially an 
  165. assembler version of the C file, providing names (constants) for typical 
  166. GEM things, and defining the standard GEM structures (as offsets). (As of
  167. v1.3, the GEMFAST.SH file is contained in the AESFAST source code ARC, not
  168. in the normal runtime ARC file).
  169.  
  170. ---------------------------------------------------------------------------
  171. 6.0                               NOTES
  172. ---------------------------------------------------------------------------
  173.  
  174. Stack usage:  The AES bindings use 20-50 bytes of stack space during a 
  175. function call, this should be totally transparent to your application.  
  176. The VDI bindings use about 50 bytes for most calls, but for the 
  177. graphics-text calls (v_gtext, etc), the stack usage will be 50 bytes + 
  178. 2*stringlength.  Still, given a maximum likely output string of 128 
  179. chars, the stack usage is around 300 bytes to process the call.  I 
  180. typically use a 1k stack, and have never had an overflow.
  181.  
  182. Register usage:  A call to any AES, VDI, or utility function will modify 
  183. registers d0-d2/a0-a1.  (as of v1.0:  register a2 is not touched by the 
  184. bindings or utils, to insure Laser C compatibility).  All other registers 
  185. are preserved if used by the binding.
  186.  
  187. VDI variables:  
  188.  
  189. The VDI bindings contain no global variable names which 
  190. can be used by the calling program (other than the function names 
  191. themselves).  This is because there is no fixed storage (data or bss) 
  192. used by the VDI bindings; each VDI call builds temporary arrays (vdipb, 
  193. contrl, intin, etc) on the stack at runtime.  The implication of this for
  194. the C programmer is that you do NOT have to code the contrl, intin, intout,
  195. ptsin, or ptsout arrays into your C program.
  196.  
  197. AES variables:  
  198.  
  199. The AES bindings define several of the required parameter blocks in BSS
  200. storage, since the parm blocks must hold static information between calls.
  201. As of GEMFAST v1.2, globally-visible names have been given to the parm
  202. blocks, and the variables within them, to allow access from the C source
  203. code level.  This has been done primarily to give access to the GEM version
  204. number, which can be a significant issue now that TOS 1.4 is a reality.
  205.  
  206. The following is the complete list of globally visible variable names:
  207.  
  208.     aespb          - The AES parmameter block, pointers to the other 
  209.                      parameter and control structures.   
  210.     aescontrol     - The AES 'control' structure, which holds the counts
  211.                      of items in the other structures, and the AES opcode.
  212.     global         - A name for the whole 'global' array/structure.
  213.     gl_apversion   - The AES version number.
  214.     gl_apcount     - The max # of GEM aps that can be active at once.
  215.     gl_apid        - The application ID.
  216.     gl_apprivate   - A longword of anything the ap wants it to be.
  217.     gl_aptree      - Pointer to the resource rs_trindex array.
  218.     gl_aprsvd      - Array of 4 longwords reserved for future use.
  219.                      (First longword is used by AES as a pointer to the
  220.                      rshdr structure when a resource file is loaded.  The
  221.                      word following this pointer is the resource length
  222.                      in bytes.)
  223.     
  224. You can use these in your C code by defining:
  225.    
  226.    extern int global[];                           /* this is one way. */
  227.    
  228.    extern int gl_apversion, gl_apid, /* etc */ ;  /* this is another. */
  229.    
  230.    extern struct {                                /* yet a third way. */
  231.      int  gl_apversion, 
  232.           gl_apcount, 
  233.           gl_apid;
  234.      long gl_apprivate;                     
  235.      long *gl_apprtree;
  236.      RSH  *gl_aprsvd;                       
  237.      } global;                              
  238.      
  239. If you use the structure, remember to access vars via global.gl_apid, etc.
  240.   
  241. The data in these global variables is not valid until after the 
  242. appl_init() call has been made.
  243.  
  244. The TOS 1.4 release notes say that the appl_init() call will place a
  245. value of $0130 in global[0] under TOS 1.4.  I found that my ROM TOS 1.0
  246. returns a value of $0120, whereas running the beta RAM TOS 1.4 returned
  247. $0104.  
  248.  
  249. Supervisor mode:  It doesn't work.  This is not my restriction, it's 
  250. just an undocumented fact about the ST's implementation of GEM, so I 
  251. thought I'd mention it.  There are workarounds available, by the way.  
  252. The problem is not in supervisor mode itself, but rather the fact that 
  253. GEM always saves registers onto the user stack.
  254.  
  255. There are more notes available in the source code modules AES@NOTES and 
  256. VDI@NOTES, and in the release notes document.  Release notes are cumulative,
  257. that is, the v1.2 release notes will contain the notes from v1.1.
  258.  
  259. ---------------------------------------------------------------------------
  260. 7.0                                BUGS
  261. ---------------------------------------------------------------------------
  262.  
  263. Undoubtedly there are some...especially in the VDI code and the rarer 
  264. AES functions.  I made no attempt to exhaustively test these libraries, 
  265. I just recompiled all my old GEM programs (about fifty of them) and 
  266. made sure they still worked.  The common functions (objc_draw, etc) are 
  267. sure to work.  If anybody wants to write verification suites for VDI and 
  268. AES, I'll be happy to use them to make these bindings bulletproof. Which 
  269. brings us to...
  270.  
  271. ---------------------------------------------------------------------------
  272. 8.0                              SUPPORT
  273. ---------------------------------------------------------------------------
  274.  
  275. I do intend to support these libraries, and to fix all bugs as soon as 
  276. they're reported.  When reporting a bug, please provide the following 
  277. info:
  278.  
  279.      - A description of the bug/symptoms.
  280.      - THE VERSION OF GEMFAST YOU ARE USING - this is important!
  281.      - The source code that leads to the bug (if the program is huge, 
  282.        please just send a suitable code fragment).
  283.  
  284. On BIX, my userid is 'ianl'.  
  285.  
  286. You can also route bug reports through your normal channel for support 
  287. on the Sozobon C compiler (on GEnie, CIS, etc), and it will get back to 
  288. me eventually.  To reach me via snail-mail, please address it to:
  289.  
  290.      Ian Lepore
  291.      6762 Marshall St.
  292.      Arvada CO   80003-4030
  293.      
  294. ---------------------------------------------------------------------------
  295. 9.0                        ABOUT THE COPYRIGHT
  296. ---------------------------------------------------------------------------
  297.  
  298. There is none.  At the last minute I changed my mind about this issue, 
  299. so just ignore any copyright statements that might still exist within 
  300. the source code modules.  
  301.  
  302. You can do anything you want with this code, source or object, but be 
  303. aware that I'm not going to support umpty-hundred modified versions of 
  304. these libraries.  If you make modifications, please distribute them 
  305. under a different name (or, send me the mods for inclusion in the next 
  306. version, then I'll support them).  
  307.  
  308. I would like to ask that the entire package by distributed as a whole, 
  309. with docs included.  (Er, that is...don't break down any of the ARC files
  310. and distribute the contents separately.  I've already broken it down such
  311. that the source is a separate piece, etc).
  312.  
  313. ; end of doc
  314.  
  315.